在线发布¶
在本地新建sphinx工程后，将本地文档发送到github上，然后就可以在readthedocs上发布在线文档
readthedocs在github有一个模板文档工程
生成的在线文档：Welcome to Read the Docs Template’s documentation!
上传文档¶
参考：Importing Your Documentation
上传地址：import
如果使用github账号登录，那么可以直接在页面上显示你的工程（需要刷新）；否则，需要手动导入
注意１：不需要上传build目录，在readthedocs导入时会自动编译
注意２：对于已经导入的工程，只要github上有更新，那么会自动触发readthedocs更新，不再需要手动操作
编译过程¶
如果你上传的是sphinx工程，那么readthedocs首先会在doc或docs文件夹内搜索conf.py文件，然后是在其他位置，如果没有会自动生成一个
readthedocs完整的编译流程如下：
- 从
github中check out代码，如果已经下载，那么更新代码 - 根据你选择的生成格式（比如
sphinx html）进行编译 - 将编译完成后的文件从构建服务器复制到应用服务器，复制完成后，就开始工作
如果要修改为mkdocs工程，可以在高级设置中选择文档类型为Mkdocs
编译问题¶
参考：
解决UnicodeDecodeError: 'ascii' codec can't decode byte 0xe5 in position 108: ordinal not in range(128
Python3异常-AttributeError: module 'sys' has no attribute 'setdefaultencoding'
编译conf.py文件时，发生中文格式问题
Running Sphinx v1.7.9
WARNING: the config value 'epub_title' is set to a string with non-ASCII characters; this can lead to Unicode errors occurring. Please use Unicode strings, e.g. u'Content'.
WARNING: the config value 'project' is set to a string with non-ASCII characters; this can lead to Unicode errors occurring. Please use Unicode strings, e.g. u'Content'.
loading translations [en]... done
making output directory...
...
...
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe5 in position 0: ordinal not in range(128)
Encoding error:
'ascii' codec can't decode byte 0xe5 in position 0: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-VIWOpI.log, if you want to report the issue to the developers.
有两种解决方法：
第一种是针对python2，在conf.py中如下代码，将编码格式改为utf-8
import sys
reload(sys)
sys.setdefaultencoding('utf8')
第二种是修改readthedocs编译环境，在Admin->Advanced Settings->Python interpreter:
将选项修改成CPython 3.x